hhkb
AI

에이전트시스템_03_에이전트 가독성과 저장소 구조

작성자 : Heehyeon Yoo|2026-03-26
# 에이전트시스템# 에이전트가독성# 저장소구조# 시스템오브레코드# 문서화

1. 에이전트가 읽을 수 없는 것은 없는 정보에 가깝다

OpenAI 글에서 가장 인상적인 표현 중 하나는 agent legibility다. 뜻은 단순하다. 에이전트가 실행 중에 읽을 수 없는 정보는, 시스템 안에 있어도 사실상 없는 정보와 비슷하다는 것이다. 사람 머릿속에만 있는 규칙, 채팅방에만 남아 있는 합의, 외부 문서에만 적힌 설계 이유는 에이전트에게 전달되지 않는다.

이 관점은 생각보다 중요하다. 사람 중심 개발에서는 이런 암묵지가 어느 정도 버틴다. 팀원이 물어보면 답해 줄 수 있고, 리뷰 과정에서 보충할 수도 있다. 하지만 에이전트는 그런 식으로 보완하지 못한다. 실행 시점에 찾을 수 있는 정보만 가지고 판단한다. 그래서 저장소 안의 정보 구조가 곧 에이전트의 작업 한계를 정하게 된다.

결국 에이전트 가독성은 문서를 많이 쓰자는 얘기가 아니다. 필요한 정보가 실제로 발견 가능하고, 이어서 읽을 수 있고, 실행 맥락과 연결되어 있어야 한다는 뜻이다.

2. 거대한 지침서보다 짧은 입구가 낫다

OpenAI가 AGENTS.md를 거대한 백과사전처럼 쓰지 않고 짧은 진입점으로 둔 이유도 여기 있다. 큰 지침서 하나에 모든 규칙을 몰아넣으면 당장은 편해 보여도 오래 가지 못한다. 문맥은 금방 비대해지고, 무엇이 중요한지 구분이 흐려지고, 문서가 낡아도 어디가 틀렸는지 검증하기가 어렵다.

그래서 더 나은 방식은 작은 입구와 깊은 문서 구조다. 짧은 AGENTS.md는 "여기서부터 읽어라"를 알려 주는 지도 역할을 한다. 실제 설계, 제품 요구사항, 실행 계획, 기술 부채, 품질 기준은 각 문서로 분리되어 저장소 안에 남는다. 에이전트는 한 번에 모든 걸 들고 시작하는 게 아니라, 필요한 만큼 찾아 들어간다.

이 방식이 좋은 이유는 사람에게도 익숙하기 때문이다. 새 팀원이 들어왔을 때도 필요한 건 백과사전보다 지도다. 지금 이 코드베이스가 어떤 구조인지, 어느 문서가 기준인지, 무엇이 최신 정보인지 먼저 잡혀야 한다. 에이전트도 크게 다르지 않다.

3. 저장소는 system of record가 되어야 한다

OpenAI가 저장소를 system of record로 본다는 말은 단순한 비유가 아니다. 계획, 설계, 품질 기준, 기술 부채 같은 운영 정보까지 저장소 안에 버전 관리되는 산출물로 남겨야 한다는 뜻이다. 그래야 에이전트가 코드만 보는 것이 아니라, 왜 이런 구조가 되었는지까지 함께 읽을 수 있다.

이 관점이 중요한 이유는 실행 계획과 결정 기록이 코드만큼 중요해지기 때문이다. 작은 수정은 짧은 계획으로 끝날 수 있지만, 큰 작업은 active plan, completed plan, debt tracker 같은 구조가 있어야 계속 이어진다. 세션이 끊기고 에이전트가 바뀌어도 작업을 다시 잡을 수 있는 이유가 여기에 있다.

여기서 핵심은 문서를 보관하는 데 있지 않다. 기계적으로 검증 가능한 구조를 만드는 데 있다. OpenAI가 cross-link, freshness, ownership, coverage를 얘기한 것도 그래서다. 문서는 많아도 되지 않는다. 최신 상태이고, 서로 연결되어 있고, 실제 코드와 어긋나지 않아야 한다.

4. 가독성은 코드 바깥에도 걸쳐 있다

저장소 문서만 잘 정리한다고 끝나지는 않는다. 에이전트가 실제 시스템을 읽을 수 있어야 한다는 문제가 그대로 남는다. OpenAI가 UI를 에이전트가 직접 띄워 보고, 로그와 메트릭을 조회하고, 그 결과를 다시 코드 수정으로 연결하게 만든 이유가 여기에 있다.

이건 꽤 큰 차이다. 에이전트가 코드만 읽는다면 실행 결과는 결국 사람의 설명을 다시 받아야 한다. 반면 UI, 로그, 메트릭, 테스트가 모두 에이전트가 접근 가능한 형태로 열려 있으면, 에이전트는 코드 변경과 실행 확인을 하나의 루프로 묶을 수 있다. "서비스 시작 시간이 800ms 아래로 내려갔는가", "이 사용자 경로에서 span이 2초를 넘는가" 같은 질문이 실제 작업 단위가 되는 이유도 여기 있다.

그래서 agent legibility는 문서의 문체 문제가 아니다. 저장소, 도구, 관측 가능성, 테스트 환경까지 포함한 실행 가능성의 문제다. 에이전트가 읽을 수 있어야 고칠 수 있고, 고칠 수 있어야 긴 작업을 혼자 이어 갈 수 있다.

5. 좋은 구조는 읽기 쉽고 강제 가능해야 한다

OpenAI 글에서 또 눈에 띄는 건 architecture와 taste를 문서만으로 두지 않았다는 점이다. 좋은 규칙은 적어 두는 것만으로는 오래 유지되지 않는다. 결국 lint, structural test, CI 같은 기계적 강제가 필요하다. 그래야 저장소 구조가 설명에 그치지 않고 실제 제약으로 작동한다.

이 부분이 중요하다. 에이전트 시스템에서는 자유를 넓게 주는 것보다, 경계를 분명하게 두는 편이 보통 더 강하다. 어떤 계층이 어디를 참조할 수 있는지, 어떤 로깅 형식을 지켜야 하는지, 어떤 파일 크기를 넘기면 안 되는지 같은 규칙이 기계적으로 적용되면, 에이전트는 그 안에서 더 빠르게 움직인다.

결국 에이전트 가독성과 저장소 구조는 문서 정리 습관이 아니다. 에이전트가 계속 읽고, 검증하고, 수정할 수 있는 작업장을 만드는 일에 가깝다. 저장소가 읽기 쉽고, 실행 환경이 관측 가능하고, 규칙이 기계적으로 강제될 때 비로소 긴 자율 작업이 덜 흔들린다.

참고 자료